home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #4 / Amiga Plus CD - 2000 - No. 4.iso / Tools / Commo-Support / Disk-Archive / includes-1_4.dms / includes-1_4.adf / doc.zoo / cx_lib.doc < prev    next >
Encoding:
Text File  |  1989-12-19  |  14.7 KB  |  480 lines
  1. TABLE OF CONTENTS
  2.  
  3. cx.lib/ArgArrayDone
  4. cx.lib/ArgArrayInit
  5. cx.lib/ArgInt
  6. cx.lib/ArgString
  7. cx.lib/CxCustom
  8. cx.lib/CxDebug
  9. cx.lib/CxFilter
  10. cx.lib/CxSender
  11. cx.lib/CxSignal
  12. cx.lib/CxTranslate
  13. cx.lib/CxTypeFilter
  14. cx.lib/HotKey
  15. cx.lib/InvertString
  16. cx.lib/ArgArrayDone                                       cx.lib/ArgArrayDone
  17.  
  18.   NAME   ArgArrayDone()      ---   SCANNED LIBRARY
  19.  
  20.     ArgArrayDone();
  21.  
  22.     void ArgArrayDone(void);
  23.  
  24.   DESCRIPTION
  25.     This function closes the disk object and Icon Library opened
  26.     by ArgArrayInit().  Don't call this until you are done using
  27.     the ToolTypes argument strings.
  28.  
  29.   DIAGNOSTICS
  30.     None.
  31.  
  32.   SEE ALSO
  33.     ArgArrayInit()
  34.  
  35. cx.lib/ArgArrayInit                                       cx.lib/ArgArrayInit
  36.  
  37.   NAME   ArgArrayInit   --   SCANNED LIBRARY
  38.  
  39.     ttypes = ArgArrayInit(argc, argv);
  40.  
  41.     char **ArgArrayInit(int,char **);
  42.  
  43.   DESCRIPTION
  44.     This function is not part of "commodities.library," but is
  45.     in "cx.lib."
  46.    
  47.     ArgArrayInit() returns a null-terminated array
  48.     of strings suitable for sending to the icon.library function
  49.     FindToolType().  This array will be the ToolTypes array of the
  50.     program's icon, if it was started from the workbench.  It will
  51.     be just 'argv' if the program was started from the CLI.
  52.    
  53.     NOTE WELL: Your C compiler must null terminate '*argv[]' for this
  54.     scheme to work.
  55.  
  56.     Pass ArgArrayInit() your startup arguments passed to main().
  57.    
  58.     ArgArrayInit() opens the icon.library (even if the caller was
  59.     started from a CLI, so that the function FindToolType() can 
  60.     be used) and may call GetDiskObject(), so clean up is necessary
  61.     when the strings are no longer needed.  The function ArgArrayDone()
  62.     does just that.
  63.    
  64.     Use of these routines facilitates the use of ToolTypes or command
  65.     line arguments to control end-user parameters in Commodities 
  66.     applications.  For example, a filter used to trap a keystroke for
  67.     popping up a window might be created by something like this:
  68.  
  69.     char   *ttypes = ArgArrayInit(argc, argv);
  70.     CxObj   *filter   = UserFilter(ttypes, "POPWINDOW", "alt f1");
  71.  
  72.     ... with ...
  73.  
  74.     CxObj   *
  75.     UserFilter(tt, action_name, default_descr)
  76.     char   **tt;             \* null-terminated (char *(*)[])   *\
  77.     char   *action_name;     \* name of your semantic action      *\
  78.     char   *default_descr;   \* used if user doesn't provide      *\
  79.     {
  80.        char   *desc;
  81.  
  82.        desc = FindToolType(tt, action_name);
  83.  
  84.        return ( CxFilter(desc? desc: default_descr) );
  85.     }
  86.  
  87.     In this way the user can assign "alt f2" to the action by
  88.     entering a tooltype in the programs icon of the form:
  89.  
  90.        POPWINDOW=alt f2
  91.  
  92.     or by starting the program from the CLI with like so:
  93.  
  94.        myprogram "POPWINDOW=alt f2"
  95.  
  96.   DIAGNOSTICS
  97.     ArgArrayInit() would return NULL if any problems occured.
  98.  
  99.   SEE ALSO
  100.     ArgArrayDone()
  101.     ArgString()
  102.     ArgInt()
  103.     icon.library/FindToolType()
  104.     cx_support.lib probably will have UserFilter().
  105.  
  106. cx.lib/ArgInt                                                   cx.lib/ArgInt
  107.  
  108.   NAME   ArgInt()      ---   SCANNED LIBRARY
  109.  
  110.     value = ArgInt(tt, string, defaultval)
  111.  
  112.     int ArgInt(char **,char *,int);
  113.  
  114.   DESCRIPTION
  115.     This function looks in the ToolTypes array 'tt' returned
  116.     by ArgArrayInit() for the entry for 'string' and returns
  117.     the "value" for 'string.'  The entry and value have the
  118.     standard ToolTypes format such as:
  119.   
  120.        ENTRY=Value
  121.   
  122.     In the case of this function, value will be passed through
  123.     'atoi()' before returning.
  124.  
  125.     If an entry for 'string' is not found, the integer 'defaultval'
  126.     will be returned.
  127.  
  128.   DIAGNOSTICS
  129.     None.
  130.  
  131.   SEE ALSO
  132.     ArgArrayInit()
  133.  
  134. cx.lib/ArgString                                             cx.lib/ArgString
  135.  
  136.   NAME   ArgString()      ---   SCANNED LIBRARY
  137.  
  138.     string = ArgString(tt, string, defaultstring)
  139.  
  140.     char *ArgString(char **,char *,char *);
  141.  
  142.   DESCRIPTION
  143.     This function looks in the ToolTypes array 'tt' returned
  144.     by ArgArrayInit() for the entry for 'string' and returns
  145.     the "value" for 'string.'  The entry and value have the
  146.     standard ToolTypes format such as:
  147.   
  148.        ENTRY=Value
  149.   
  150.     If an entry for 'string' is not found, the defaultstring
  151.     will be returned.
  152.  
  153.   DIAGNOSTICS
  154.     None.
  155.  
  156.   SEE ALSO
  157.     ArgArrayInit()
  158.  
  159. cx.lib/CxCustom                                               cx.lib/CxCustom
  160.  
  161.   NAME   CxCustom()   --   MACRO
  162.  
  163.     custom = CxCustom(action, id);
  164.  
  165.     CxObj *CxCustom(LONG(*)(),LONG);
  166.    LONG   (*action)();
  167.  
  168.   DESCRIPTION
  169.     This function creates a custom Commodities object.  The action
  170.     of this object on receiving a Commodities message is to
  171.     call a function of the application programmer's choice.
  172.    
  173.     The function provided ('action') will be passed a pointer to
  174.     the actual commodities message (in commodities private data
  175.     space), and will actually execute as part of the input handler
  176.     system task.  Among other things, the value of 'id' can be
  177.     recovered from the message by using the function CxMsgID().
  178.    
  179.     The purpose of this function is two-fold.  First, it allows
  180.     programmers to create Commodities Exchange objects with
  181.     functionality that was not imagined or chosen for inclusion
  182.     by the designers.  Secondly, this is the only way to act
  183.     synchronously with Commodities. 
  184.    
  185.     For further explanation and examples, consult the Reference
  186.     Manual.
  187.  
  188.     This function is a C-language macro for CreateCxObj(), defined
  189.     in "cxfunctions.h."
  190.  
  191.   DIAGNOSTICS
  192.     Returns NULL if the custom object cannot be created.
  193.  
  194.   SEE ALSO
  195.     CreateCxObj()
  196.     Custom Objects (in Reference Manual)
  197.     CxMsgID()
  198.  
  199. cx.lib/CxDebug                                                 cx.lib/CxDebug
  200.  
  201.   NAME   CxDebug()   --   MACRO
  202.  
  203.     debugger = CxDebug(id);
  204.  
  205.     CxObj *CxDebug(LONG);
  206.  
  207.   DESCRIPTION
  208.     This function creates a Commodities debug object.  The action
  209.     of this object on receiving a Commodities message is to
  210.     print out information about the Commodities message through
  211.     the Serial port (using the kprintf() routine).  The value
  212.     'id' will also be displayed.
  213.    
  214.     Note that this is a synchronous occurence (the printing
  215.     is done by the input device task).  If screen or file
  216.     output is desired, using a sender object instead of
  217.     debug object is necessary, since such output is best
  218.     done by your application process.
  219.  
  220.     This function is a C-language macro for CreateCxObj(), defined
  221.     in "cxfunctions.h."
  222.  
  223.   DIAGNOSTICS
  224.     Returns NULL if the debug object cannot be created.
  225.  
  226.   SEE ALSO
  227.     CreateCxObj()
  228.     CxSender()
  229.     exec_support/kprintf()
  230.  
  231. cx.lib/CxFilter                                               cx.lib/CxFilter
  232.  
  233.   NAME   CxFilter()   --   MACRO
  234.  
  235.     filter = CxFilter(description);
  236.  
  237.     CxObj *CxFilter(BYTE *);
  238.  
  239.   DESCRIPTION
  240.     Creates an input event filter object which matches Commodities
  241.     Input Messages fitting the 'description' string.  If
  242.     'description' is NULL, the filter will not match any messages.
  243.    
  244.     A filter may be modified by the functions SetFilter(), using
  245.     a description string, and SetFilterIX(), which takes a 
  246.     binary Input Expression as a parameter.
  247.    
  248.     This function is a C-language macro for CreateCxObj(), defined
  249.     in "cxfunctions.h."
  250.  
  251.   DIAGNOSTICS
  252.     Returns NULL if the function fails, which only occurs
  253.     if there is no memory for the new filter object.  If there
  254.     is a problem in the description string, the internal error
  255.     code of the filter object will be set to so indicate.  This
  256.     error code may be interrogated using the function CxObjError().
  257.  
  258.   SEE ALSO
  259.     CreateCxObj()
  260.     SetFilter(), SetFilterIX(), CxObjError()
  261.     Objects and Message (in Reference Manual)
  262.     Input Expressions and Description Strings
  263.     Objects and Messages (in Reference Manual)
  264.     Error Handling   (in Reference Manual)
  265.  
  266. cx.lib/CxSender                                               cx.lib/CxSender
  267.  
  268.   NAME   CxSender()   --   MACRO
  269.  
  270.     sender = CxSender(port, id)
  271.  
  272.     CxObj *CxSender(struct MsgPort *,LONG);
  273.  
  274.   DESCRIPTION
  275.     This function creates a Commodities sender object.  The action
  276.     of this object on receiving a Commodities message is to
  277.     copy the Commodities message into a standard Exec Message,
  278.     to put the value 'id' in the message as well, and to send the
  279.     message off to the Message Port 'port.'
  280.   
  281.     The value 'id' is used so that an application can monitor
  282.     messages from several senders at a single port.  It can
  283.     be retrieved from the Exec message by using the function
  284.     CxMsgID(). The value can be a simple integer ID, or a pointer
  285.     to some application data structure, for example.
  286.   
  287.     Note that Exec messages sent by sender objects arrive
  288.     asynchronously at the destination port.  Do not assume 
  289.     anything about the status of the Commodities message which
  290.     was copied into the Exec message you received.
  291.  
  292.     All Exec messages sent to your ports must be replied.
  293.     Messages may be replied after the sender object has been
  294.     deleted.
  295.   
  296.     This function is a C-language macro for CreateCxObj(), defined
  297.     in "cxfunctions.h."
  298.  
  299.   DIAGNOSTICS
  300.     Returns NULL if the sender object cannot be created.
  301.  
  302.   SEE ALSO
  303.     CreateCxObj()
  304.     exec.library/PutMsg(), exec.library/ReplyMsg()
  305.     CxMsgID()
  306.  
  307. cx.lib/CxSignal                                               cx.lib/CxSignal
  308.  
  309.   NAME   CxSignal()   --   MACRO
  310.  
  311.     signaler = CxSignal(task, signal);
  312.  
  313.     CxObj *CxSignal(struct Task *,LONG);
  314.  
  315.   DESCRIPTION
  316.     This function creates a Commodities signal object.  The action
  317.     of this object on receiving a Commodities message is to
  318.     send the 'signal' to the 'task.'  The caller is responsible
  319.     for allocating the signal and determining the proper task ID.
  320.   
  321.     Note that 'signal' is the signal value as returned by
  322.     AllocSignal() (example: 3) , not the mask made from
  323.     that value (i.e., not binary 0000000000001000).
  324.   
  325.     This function is a C-language macro for CreateCxObj(), defined
  326.     in "cxfunctions.h."
  327.  
  328.   DIAGNOSTICS
  329.     Returns NULL if the object could not be created.
  330.  
  331.   SEE ALSO
  332.     CreateCxObj()
  333.     Objects and Messages (in Reference Manual)
  334.     exec.library/Signal(), exec.library/AllocSignal(),
  335.     exec.library/FindTask()
  336.  
  337. cx.lib/CxTranslate                                         cx.lib/CxTranslate
  338.  
  339.   NAME   CxTranslate()   --   MACRO
  340.  
  341.     translator = CxTranslate(ie);
  342.  
  343.     CxObj *CxTranslate(struct InputEvent *);
  344.  
  345.   DESCRIPTION
  346.     This function creates a Commodities 'translate' object. 
  347.     The action of this object on receiving a Commodities
  348.     message is to replace that message in the commodities network
  349.     with a chain of Commodities input messages.
  350.   
  351.     One new Commodities input message for each input event
  352.     in the linked list starting at 'ie' (and NULL terminated).
  353.     The routing information of the new input messages will be
  354.     copied from the input message they replace.
  355.   
  356.     The linked list of input events associated with a translate
  357.     object can be changed using the SetTranslate() function.
  358.   
  359.     If 'ie' is NULL, the null translation occurs: that is, the
  360.     original commodities input message is disposed, and no
  361.     others are created to take its place.
  362.   
  363.     This function is a C-language macro for CreateCxObj(), defined
  364.     in "cxfunctions.h."
  365.  
  366.   DIAGNOSTICS
  367.     Returns NULL if the translate object cannot be created.
  368.  
  369.   SEE ALSO
  370.     CreateCxObj()
  371.     SetTranslate()
  372.     Commodities Input Messages and Filters
  373.  
  374. cx.lib/CxTypeFilter                                       cx.lib/CxTypeFilter
  375.  
  376.   NAME   CxTypeFilter()   --   MACRO
  377.  
  378.     typef = CxTypeFilter(typemask);
  379.  
  380.     CxObj *CxTypeFilter(LONG);
  381.  
  382.   DESCRIPTION
  383.     Creates a Commodities Object similar to CxFilter(), but one
  384.     that diverts all Commodities messages whose type, which is
  385.     always a power of two, matches a bit set in 'typemask.'
  386.   
  387.     Values of message types are given in "cxusr.h."
  388.   
  389.     This function is a C-language macro for CreateCxObj(), defined
  390.     in "cxfunctions.h."
  391.  
  392.   DIAGNOSTICS
  393.     Returns NULL if the function fails, which only occurs
  394.     if there is no memory for the new filter object.  If there
  395.     is a problem in the description string, the internal error
  396.     code of the filter object will be set to so indicate.  This
  397.     error code may be interrogated using the function CxObjError().
  398.  
  399.   SEE ALSO
  400.     CreateCxObj()
  401.     SetFilter(), SetFilterIX(), CxObjError()
  402.     Object and Messages (in Reference Manual)
  403.     Input Expressions and Description Strings
  404.     Error Handling
  405.  
  406. cx.lib/HotKey                                                   cx.lib/HotKey
  407.  
  408.   NAME   HotKey()  --   SCANNED LIBRARY
  409.  
  410.     filter = Hotkey(descr, port, ID);
  411.  
  412.     CxObj *HotKey(char *,struct MsgPort *,LONG);
  413.  
  414.   DESCRIPTION
  415.     This function is not part of "commodities.library," but
  416.     is in the scanned library cx_support.lib.  It creates
  417.     a triad of Commodities objects to accomplish a high-level
  418.     function.
  419.   
  420.     The three objects are a filter, which is created to match
  421.     by the call CxFilter(descr), a sender created by the call
  422.     CxSender(port, ID), and a translator which is created by
  423.     CxTranslate(NULL), so that it swallows any Commodities
  424.     input event messages that are passed down by the filter.
  425.   
  426.     This is the simple way to get a message sent to your program
  427.     when the user performs a particular input action.
  428.   
  429.     It is strongly recommended that the ToolTypes environment
  430.     be used to allow the user to specify the input descriptions
  431.     for your application's hotkeys.
  432.  
  433.   DIAGNOSTICS
  434.     Returns NULL and cleans up after itself if any problems occur
  435.     creating the objects.  It may be wise to test filter using
  436.     CxObjError() to insure that 'descr' was a valid description.
  437.  
  438.   SEE ALSO
  439.     ToolTypes and the Commodities Environment (in Reference Manual)
  440.     CxFilter(), CxSender(), CxTranslate(), CxObjError()
  441.  
  442. cx.lib/InvertString                                       cx.lib/InvertString
  443.  
  444.   NAME   InvertString()   --   SCANNED LIBRARY
  445.  
  446.     event =InvertString(str, km)
  447.  
  448.     struct InputEvent *InvertString(UBYTE *,CPTR *);
  449.  
  450.   DESCRIPTION
  451.     This function returns a linked list of input events which would
  452.     translate into the string using the keymap 'km' (of the system
  453.     default keymap if 'km' is NULL).
  454.    
  455.     The null-terminated 'str' may contain:
  456.     -ANSI character codes
  457.     -backslash escaped characters: 
  458.        \n   -   return
  459.        \r   -   return
  460.        \t   -   tab
  461.        \0   -   don't use this, ok?
  462.        \\   -   backslash
  463.     -a text description of an input event as used by ParseIX(),
  464.      enclosed in angle brackets.
  465.  
  466.     An example is:
  467.        abc<alt f1>\nhi there.
  468.    
  469.     NOTE: you are responsible for freeing the InputEvents that this
  470.     function allocates.  You may use FreeIEvents().
  471.  
  472.   DIAGNOSTICS
  473.     Returns NULL if there is a problem, most often an illegal description
  474.     enclosed in angles.
  475.  
  476.   SEE ALSO
  477.     ParseIX()
  478.     FreeIEvents()
  479.  
  480.